Add LiveReload functionality to Jekyll. #5142

awood · 2016-07-27T18:33:58Z

Invoke using jekyll serve --livereload. The Serve command will inject
some necessary JavaScript links into pages. When loaded in a browser,
this JavaScript opens a connection over port 35729 using WebSockets to
an EventMachine reactor listening to that port in a separate thread.

When Jekyll finishes rendering a page, --livereload hooks create a
JSON message with the relative URL of the refreshed page. This message
is then pushed to the browser over the WebSockets connection. The
client-side JavaScript then reloads the page if the URL in the message
matches the URL of the current page.

Implements #4644

awood · 2016-07-27T18:46:02Z

This PR doesn't include any significant documentation on the feature, but I figured I'd wait until some of the details get hammered out before writing anything.

Other notes:

It may be desirable to prune the number of options available to configure LiveReload. Specifically, the Flash version for browsers that don't support WebSockets might be worth dropping since no one is going to be developing there Jekyll site in Android and the overlap of IE 8 only users and Jekyll users is probably pretty small.
The semantics around --ignore are weird could probably lead to false bug reports. From my experiments and reading of the JavaScript (which I did not write), if any portion of URL the browser is pointed to matches the URL to reload in the JSON message, the browser will refresh. This is especially noticeable on index pages ("/blog/" would match every refresh message for pages in the directory)
The tests are very much functional tests instead of unit tests. In my opinion the functionality is complex enough to merit it, but others may disagree.

envygeeks · 2016-07-27T19:01:25Z

lib/jekyll/commands/serve.rb

+            "Skips the initial site build which occurs before the server is started."],
+          "livereload"         => ["-l", "--livereload",
+            "Use LiveReload to automatically refresh browsers"],
+          "swf"                => ["--swf", "Use Flash for WebSockets support"],


This is a no-go. Everybody is dropping support for flash faster than we want to turn around and have to remove it.

awood · 2016-07-27T19:09:26Z

@envygeeks do you want revisions as separate commits to squash merge or for me to just adjust this current commit?

envygeeks · 2016-07-27T19:10:37Z

@awood whatever works best for you and allows you to flow the best! We normally only ask for a rebase just before we merge it, before that, it's whatever workflow you wish to use since Github now has that fancy "view all files changed".

envygeeks · 2016-07-27T19:12:03Z

I kinda like this, maybe we should add an updater like we've for normalize.css so that we can auto-update it every once in a while as it'll be quite easy to forget it exists. Other than that just a few comments and we can do another deeper review.

awood · 2016-07-27T19:37:24Z

I kinda like this, maybe we should add an updater like we've for normalize.css so that we can auto-update it every once in a while as it'll be quite easy to forget it exists. Other than that just a few comments and we can do another deeper review.

So you automatically pull the file every so often? That's a really good idea. I think I will need to modify the code somewhat because it's been modified slightly to read from variables defined in the inserted script tags, but I think I can figure something else out so the stock livereload.js will work

awood · 2016-07-28T18:58:31Z

So you automatically pull the file every so often? That's a really good idea. I think I will need to modify the code somewhat because it's been modified slightly to read from variables defined in the inserted script tags, but I think I can figure something else out so the stock livereload.js will work

Okay, I've implemented the above. The PR now just uses the stock version of the most recent released livereload.js. Pulling it in via bower might be a good way of making sure it stays up to date, but that is something for the maintainers to decide.

awood · 2016-08-01T18:03:51Z

Looks like this is failing in JRuby. I think the issue has to do with the WebSockets server thread introduced in this PR. I'll do some investigation, but if anyone out there has some experience with the subtleties of JRuby, I'd wouldn't mind a second opinion.

awood · 2016-08-02T21:12:48Z

So I've made some changes for JRuby, but JRuby's TLS support is broken. I can either remove the TLS support for the WebSockets connection entirely or just ignore those options when running under JRuby (not sure if that's an acceptable solution though).

Additionally, while the tests pass, the actual functionality under JRuby is broken. For whatever reason, the message to reload is sent but the browser doesn't react. I'll look into this issue later and try and get some tests that actually ensure receipt of the reload command.

awood · 2016-09-20T14:57:11Z

I have tracked the JRuby functionality issue down to a problem within either EM-Websocket or EventMachine. I've filed an issue with EM-Websocket.

awood · 2016-09-20T15:01:41Z

@envygeeks the Travis failures for this PR appear to be code style releated in code that I haven't modified. Otherwise I think this PR is ready for review at least. There's an outstanding issue with EM-Websocket/EventMachine under JRuby but I don't think that should block the review process. I can go ahead and address any issues the maintenance team sees while waiting to hear back from on the issue I filed for the JRuby bug.

envygeeks · 2016-09-20T15:22:43Z

@awood I'll take some time this week to start reviewing /cc @jekyll/core @jekyll/ecosystem

awood · 2016-09-20T18:14:24Z

Looks like the JRuby issue is a known problem with an EventMachine reactor running under a thread.

awood · 2016-09-21T15:04:39Z

An alternative to having LiveReload just not work under JRuby would be to switch from WEBrick to an EventMachine compatible http server. Jekyll could then just start the EventMachine reactor when it's time to start serving and the reactor would manage both the LiveReload server on 35729 and the http server on 4000.

I actually have a working proof-of-concept using Thin as the http server, and it's pretty nice since it removes all the need for threading from Jekyll proper and just delegates everything to the EventMachine event loop. Plus EventMachine can daemonize so LiveReload would continue to work in daemon mode (whereas it does not in this PR since that would require Jekyll spinning off two processes which I thought a little dodgy especially if one process dies and the other doesn't).

The downside is that Thin doesn't run under JRuby at all. There are JRuby compatible http server (notably Puma) but they aren't EventMachine based and so there would have to be some sort of low-level shim layer that brokered between EventMachine's Connection class and the http server which would probably end up being a nightmare.

But if Thin ever runs under JRuby, I think the strategy described above would be a worthwhile refactoring.

ghost

Looking good, just a few things that probably need changes. 😄

ghost · 2016-09-21T16:45:28Z

lib/jekyll/commands/serve.rb

+              validate_options(opts)
+
+              opts["watch"] = true unless opts.key?("watch")
+              opts["livereload_port"] ||= LIVERELOAD_PORT


~~You've used Hash#key? for "watch" and ||= for "livereload_port"~~

Yeah, I did that because "watch" can legitimately be false. I can line them up so they both use key. I think I tried to keep the ||= where possible because that seemed to be the preferred idiom elsewhere in the code.

Oops, my mistake! 😊

ghost · 2016-09-21T16:47:19Z

lib/jekyll/commands/serve.rb

+                " of LiveReload."
+            end
+          elsif opts["livereload_min_delay"] ||
+              opts["liverealod_max_delay"]   ||


Typo!

- opts["liverealod_max_delay"] || + opts["livereload_max_delay"] ||

ghost · 2016-09-21T16:47:48Z

lib/jekyll/commands/serve.rb

+              opts["livereload_ignore"]      ||
+              opts["livereload_port"]
+            Jekyll.logger.warn "The --livereload-min-delay, --livereload-max-delay, "\
+               "--livereoload-ignore, and --livereload-port options require the "\


Typo!

- "--livereoload-ignore, and --livereload-port options require the "\ + "--livereload-ignore, and --livereload-port options require the "\

ghost · 2016-09-21T16:52:24Z

lib/jekyll/commands/serve.rb

        def start_callback(detached)
          unless detached
            proc do
-              Jekyll.logger.info("Server running...", "press ctrl-c to stop.")
+              @running << "."


I feel that Queue is the wrong data type for this usage. Correct me if I'm wrong, but you never seem to actually wait for the Queue to become populated and even if you did, there are probably better data types for this usage.

I'm using it as a mechanism to block the test from running until the server(s) can successfully start. The only place it's actually waiting for the queue to be populated is in test_commands_serve.rb. The test starts a Serve thread and Serve starts a WEBrick thread and joins it so there's not another good way I could think of to know whether WEBrick is actually up and running.

I think Queue is the appropriate choice here; the docs say "[The Queue] class provides a way to synchronize communication between threads."

That being said, I do think that it's kind of crummy to have cruft in there that's only really used for the tests. I'm totally open to suggestions on a better way to handle this situation.

ghost · 2016-09-21T16:55:45Z

@awood

An alternative to having LiveReload just not work under JRuby would be to switch from WEBrick to an EventMachine compatible http server.
The downside is that Thin doesn't run under JRuby at all.

😆

I've never liked LiveReload but I'm sure it'll be a very useful feature for many Jekyll users.

envygeeks · 2016-09-21T16:58:57Z

I've never really found it useful, I can F5 as fast as that thing loads lol. But at this point we need to bring in @jekyll/ecosystem and @jekyll/core so they can comment on your suggestions.

ghost · 2016-09-21T18:53:09Z

But you're polling in the test, not using the actual Queue!

awood · 2017-12-06T17:14:43Z

@DirtyF Conflicts resolved

parkr · 2017-12-06T18:19:29Z

Can you skip the specs that use LiveReload on Windows if they won't work?

* Improve variable names * Improve resiliency when conflicting options are given * Refactor the LiveReloadReactor class into a separate file * Correct typos * Use alias_method for brevity * Use __dir__ instead of File.dirname(__FILE__) * Set and use default LiveReload port

awood · 2017-12-06T20:58:01Z

Can you skip the specs that use LiveReload on Windows if they won't work?

Done!

DirtyF · 2017-12-06T21:33:51Z

💯 A big thanks @awood for all the work you put into this, I hope this really improves the developer experience for a majority of Jekyll users.

@jekyllbot: merge +minor

DirtyF · 2017-12-06T21:49:43Z

@awood

If I add the --livereload option on the command line this works fine. (I only tested this before merging)

But if I add the "livereload" => "true" option to our rake file then the following message appears:

rake aborted!
NoMethodError: undefined method `start' for nil:NilClass
/Users/frank/code/jekyll/jekyll/lib/jekyll/commands/serve.rb:224:in `start_up_webrick'
/Users/frank/code/jekyll/jekyll/lib/jekyll/commands/serve.rb:104:in `process'
/Users/frank/code/jekyll/jekyll/rake/site.rake:37:in `block (2 levels) in <top (required)>'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:251:in `block in execute'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:251:in `each'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:251:in `execute'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:195:in `block in invoke_with_call_chain'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/2.4.0/monitor.rb:214:in `mon_synchronize'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:188:in `invoke_with_call_chain'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/task.rb:181:in `invoke'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:160:in `invoke_task'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:116:in `block (2 levels) in top_level'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:116:in `each'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:116:in `block in top_level'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:125:in `run_with_threads'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:110:in `top_level'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:83:in `block in run'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:186:in `standard_exception_handling'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/lib/rake/application.rb:80:in `run'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/gems/2.4.0/gems/rake-12.3.0/exe/rake:27:in `<top (required)>'
/Users/frank/.rbenv/versions/2.4.2/bin/rake:23:in `load'
/Users/frank/.rbenv/versions/2.4.2/bin/rake:23:in `<top (required)>'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli/exec.rb:75:in `load'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli/exec.rb:75:in `kernel_load'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli/exec.rb:28:in `run'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli.rb:424:in `exec'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/vendor/thor/lib/thor/command.rb:27:in `run'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/vendor/thor/lib/thor/invocation.rb:126:in `invoke_command'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/vendor/thor/lib/thor.rb:387:in `dispatch'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli.rb:27:in `dispatch'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/vendor/thor/lib/thor/base.rb:466:in `start'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/cli.rb:18:in `start'
/Users/frank/.rbenv/versions/2.4.2/bin/bundle:30:in `block in <main>'
/Users/frank/.rbenv/versions/2.4.2/lib/ruby/site_ruby/2.4.0/bundler/friendly_errors.rb:122:in `with_friendly_errors'
/Users/frank/.rbenv/versions/2.4.2/bin/bundle:22:in `<main>'
Tasks: TOP => site:preview

Merge pull request 5142

burrich · 2018-01-24T13:36:22Z

Hi, can you confirm that livereload is not supported on Windows please ?

@awood

ashmaroli · 2018-01-24T14:34:22Z

@burrich --livereload is definitely supported on Windows.. just not with --ssl_cert and --ssl_key as well..

burrich · 2018-01-24T14:58:11Z

Ok thanks @ashmaroli , i will try.

awood · 2018-01-24T15:57:40Z

@burrich If I recall correctly, it won't work with Ruby 2.4 on Windows due to a dependency (EventMachine) not working.

ashmaroli · 2018-01-24T16:06:44Z

won't work with Ruby 2.4 on Windows due to a dependency (EventMachine) not working.

@burrich That issue is being tracked here 👉 eventmachine/eventmachine#806

RobertDeRose · 2018-01-24T18:53:16Z

lib/jekyll/commands/serve.rb

+              # EventMachine's SSL support in Windows requires building the gem's
+              # native extensions against OpenSSL and that proved to be a process
+              # so tedious that expecting users to do it is a non-starter.
+              Jekyll.logger.abort_with "Error:", "LiveReload does not support SSL"


I've stepped way back from this PR, never had the time to look at it as my plugin was just working for me. However, Livereload can support SSL, I have support for it in my plugin RobertDeRose/jekyll-livereload@34df507

Thanks @RobertDeRose, I was using your plugin until now :)
Are you interested in submitting a patch?

I might, if I can find the time. So, that's a big maybe

@RobertDeRose The problem wasn't with LiveReload not supporting SSL; it was with getting EventMachine and OpenSSL to cooperated on Windows. I actually had it working fine in Linux, but getting the OpenSSL libraries to install and work on the Windows CI environment was a nightmare, so I just gave up 😭. I figured most people would only be using LiveReload for rapid prototyping so I didn't consider SSL support to be a must-have.

@awood that's a fair point, I never did testing for Windows, and to be honest, not a lot of benefit for it when developing locally, unless you really need to ensure SSL isn't messing with thing, but at that point, you don't really need live reload. OK ignore my extremely late to the party comments then.

ghost · 2018-08-03T06:24:34Z

Fixed ?

envygeeks reviewed Jul 27, 2016
View reviewed changes

awood force-pushed the livereload branch 2 times, most recently from cbfb322 to 80b4757 Compare July 29, 2016 20:15

awood force-pushed the livereload branch 2 times, most recently from 52f88a7 to 0382b3a Compare August 2, 2016 21:02

awood force-pushed the livereload branch from cffa450 to 12c4618 Compare September 19, 2016 20:29

jekyllbot assigned parkr Sep 20, 2016

envygeeks assigned envygeeks and unassigned parkr Sep 20, 2016

ghost suggested changes Sep 21, 2016

View reviewed changes

awood force-pushed the livereload branch from 2db7295 to c9c5fce Compare September 21, 2016 19:01

awood force-pushed the livereload branch from b6c2a0c to 7b72d97 Compare December 6, 2017 16:32

DirtyF added the accepted label Dec 6, 2017

DirtyF added this to the v3.7.0 milestone Dec 6, 2017

awood force-pushed the livereload branch from 7b72d97 to 69d36e6 Compare December 6, 2017 20:13

jekyllbot merged commit 9d68b1b into jekyll:master Dec 6, 2017

jekyllbot added the enhancement label Dec 6, 2017

jekyllbot added a commit that referenced this pull request Dec 6, 2017

Update history to reflect merge of #5142 [ci skip]

3efb1ad

ashmaroli mentioned this pull request Dec 7, 2017

Register reload hooks in Server#process #6605

Merged

DirtyF pushed a commit that referenced this pull request Dec 7, 2017

Add LiveReload functionality to Jekyll. (#5142)

50ff219

Merge pull request 5142

DirtyF pushed a commit that referenced this pull request Dec 7, 2017

Update history to reflect merge of #5142 [ci skip]

28e20b9

RobertDeRose reviewed Jan 24, 2018

View reviewed changes

kenchan0130 mentioned this pull request Apr 7, 2018

Cannot start up server with livereload jekyll/jekyll-admin#458

Closed

jamesluberda mentioned this pull request Jun 7, 2018

Livereload sleep #7064

Open

jamesluberda mentioned this pull request Jun 18, 2018

validate_options non-functional in serve.rb #7082

Closed

jamesluberda mentioned this pull request Jun 30, 2018

support livereload when jekyll-admin is installed jekyll/jekyll-admin#468

Merged

jekyll locked as resolved and limited conversation to collaborators Aug 3, 2018

jekyll deleted a comment Aug 3, 2018

jekyllbot added the frozen-due-to-age label Aug 3, 2019

Add LiveReload functionality to Jekyll. #5142

Add LiveReload functionality to Jekyll. #5142

Conversation

awood commented Jul 27, 2016

awood commented Jul 27, 2016

Choose a reason for hiding this comment

awood commented Jul 27, 2016

envygeeks commented Jul 27, 2016

envygeeks commented Jul 27, 2016

awood commented Jul 27, 2016

awood commented Jul 28, 2016

awood commented Aug 1, 2016

awood commented Aug 2, 2016

awood commented Sep 20, 2016

awood commented Sep 20, 2016

envygeeks commented Sep 20, 2016

awood commented Sep 20, 2016

awood commented Sep 21, 2016

ghost left a comment

Choose a reason for hiding this comment

ghost Sep 21, 2016 • edited by ghost

Choose a reason for hiding this comment

awood Sep 21, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost Sep 21, 2016 • edited by ghost

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost commented Sep 21, 2016

envygeeks commented Sep 21, 2016

ghost commented Sep 21, 2016

awood commented Dec 6, 2017

parkr commented Dec 6, 2017

awood commented Dec 6, 2017

DirtyF commented Dec 6, 2017 • edited

DirtyF commented Dec 6, 2017 • edited

burrich commented Jan 24, 2018 • edited

ashmaroli commented Jan 24, 2018

burrich commented Jan 24, 2018

awood commented Jan 24, 2018

ashmaroli commented Jan 24, 2018

RobertDeRose Jan 24, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost commented Aug 3, 2018

ghost Sep 21, 2016 •

edited by ghost

awood Sep 21, 2016 •

edited

ghost Sep 21, 2016 •

edited by ghost

DirtyF commented Dec 6, 2017 •

edited

DirtyF commented Dec 6, 2017 •

edited

burrich commented Jan 24, 2018 •

edited

RobertDeRose Jan 24, 2018 •

edited